New image_button component plus patch to support it

Patch for webform.module

New image_button component

Cool! Thanks for testing and improving.

Thanks for the questions djalloway and quickcatch. I hope the following adequately addresses them.

A minimal patch is needed to handle image buttons correctly

Drupal 6 has implemented a new way of dealing with image buttons in an attempt to deal with the fact that IE 6 does not return the value of a clicked image button. It makes use of $form_state['clicked_button']['#value']. As currently written, the webform module does not take this change into account. Thus simply converting buttons to image buttons will sometimes result in errors, especially in a case where there is more than one button on the form (for example, if there is both a back button and a submit button). So regardless of how we insert image buttons into webforms, we need to patch webform.module. See item 2 at the top of this page for a further description of my proposed fix for this issue.

What happens to the normal buttons?

They are unset when there is a corresponding image buttons. See the discussion in item 1 at the top of this page for more details.

Why a component not an advanced setting?

I often have cases where a client wants to put components both above and below the buttons. For example, they might have a contact us form where they want the user entry fields and submit button clustered together, all of them above a markup component providing information about how to contact the client by snail mail or telephone. Having the image button component makes it easy to achieve this.

It is solving this problem which I think makes the image button component solution more powerful than having image button functionality as part of the advanced settings for a web form. Advanced settings would let us use image buttons instead of regular buttons, but we would have no way of having some components above and other components below the buttons.

Why a component not a theme?

I may be wrong about this, but I don't think that any of the currently available themes would be adequate to allow having some components above the button(s), and others below the button(s).

Even if that could be achieved with a theme, that approach makes things more difficult than doing things through the UI. I believe it would be preferable if the client could do both of the following without having to edit a theme file (or hire me to edit the theme file for them):

• Change the position of an image button relative to other components on the web form: i.e. move it up or down the stack of components.
• Create a new webform which uses different button images than are used by any of the existing webforms.

I have updated the code, and attached a new patch which I very much hope satisfactorily addresses the various issues raised.

Before getting into the changes I made, I think it makes sense to be clearer about what I am and am not doing. I am not simply providing new buttons, but rather providing a means of overriding the default buttons that are already provided by webform. Although I am allowing overriding of the default buttons, I am not overriding the logic which decides what type(s) of button appear on each page. So, just like webform.module, I am supporting three types of button: previous, next, and submit. I am continuing to use webform's existing logic to determine what button(s) should be displayed on any given page of a form. This means that webform's logic, not the form administrator, has the final say as to what button types appear on each page of a form. For example, even if a form administrator puts a submit button on the middle page of a multipage form, that button will not be displayed because webform's logic says that a submit button should only go on the last page of a multipage form. Thus there is no need to worry about situations such as having a next button and a submit button on a middle page of a multipage form. (Although there may be some need to worry about form administrators being annoyed by this behavior. I leave it an open question whether it would be better if the module gave form administrators enough rope to hang themselves.)

At a functional level, this latest version has the following changes:

1) Both image buttons and regular buttons are supported. To keep both the code and the UI simple, I have done this by implementing a second component. Thus there are now two components: button and image button. These do pretty much the same thing except that one allows form administrators to override default buttons with image buttons, choosing the path to the image file, and the other allows them to override default buttons with regular buttons, choosing the text to display on the button. In either case, any button can go anywhere in the component stack, including having buttons of the same type at the top and bottom of the stack, if so desired.

2) I have slightly modified and extended the token system. Instead of %b and %t, I have implemented the following tokens: %base, %theme, and %files. I believe this covers the three main places where one would find an image file. I have opted for full name tokens instead of single letters because I think that makes things clearer to users, even if it means a little more typing.

At a code level, I have made the following changes:

1) I believe that the code now meets Drupal coding standards.

2) The latest patch is rolled against the 3.x version.

3) As suggested, I have rewritten it so it now does significant work within _webform_client_form_add_component(), and no longer loops through the entire form. In order to enable this, I have added a $button_states array which gets passed to _webform_client_form_add_component(). The button states are set by the same logic as determines which default button(s) to display on a page.

4) Although some of the module was taking advantage of the new $form_state['clicked_button'] protocol, this was not the case for the place I needed to change. I have, however, modified my change so it requires that protocol rather than making it optional. Thus I have replaced

if ($form_state['values']['op'] != $submit_op) {

with

if ($form_state['clicked_button']['#value'] != $submit_op) {

5) During my testing, I discovered that default previous buttons provided by the module were not working correctly in the 3.x version of the code. I looked into this, and discovered that the problem was that the updated module is now testing as follows

if (end($form_state['clicked_button']['#parents']) == 'prev' && $page_num > 1) {

However, the value for end($form_state['clicked_button']['#parents']) is the same as the name of the previous button's element in the form array. This was being set to "previous", and thus was never matching "prev". I have changed the name of the element in the form array to "prev". That seems to have done the trick.

Please note:

I see that the patch includes the following

- array(' ', '-', '€', 'ƒ', 'Š', 'Ž', 'š', 'ž', 'Ÿ', '¢', '¥', 'µ', 'À', 'Á', 'Â', 'Ã', 'Ä', 'Å', 'Ç', 'È', 'É', 'Ê', 'Ë', 'Ì', 'Í', 'Î', 'Ï', 'Ñ', 'Ò', 'Ó', 'Ô', 'Õ', 'Ö', 'Ø', 'Ù', 'Ú', 'Û', 'Ü', 'Ý', 'à', 'á', 'â', 'ã', 'ä', 'å', 'ç', 'è', 'é', 'ê', 'ë', 'ì', 'í', 'î', 'ï', 'ñ', 'ò', 'ó', 'ô', 'õ', 'ö', 'ø', 'ù', 'ú', 'û', 'ü', 'ý', 'ÿ', 'Œ', 'œ', 'Æ', 'Ð', 'Þ', 'ß', 'æ', 'ð', 'þ'),
+ array(' ', '-', '€', 'ƒ', 'Š', 'Ž', 'š', 'ž', 'Ÿ', '¢', '¥', 'µ', 'À', '�', 'Â', 'Ã', 'Ä', 'Å', 'Ç', 'È', 'É', 'Ê', 'Ë', 'Ì', '�', 'Î', '�', 'Ñ', 'Ò', 'Ó', 'Ô', 'Õ', 'Ö', 'Ø', 'Ù', 'Ú', 'Û', 'Ü', '�', 'à', 'á', 'â', 'ã', 'ä', 'å', 'ç', 'è', 'é', 'ê', 'ë', 'ì', 'í', 'î', 'ï', 'ñ', 'ò', 'ó', 'ô', 'õ', 'ö', 'ø', 'ù', 'ú', 'û', 'ü', 'ý', 'ÿ', 'Œ', 'œ', 'Æ', '�', 'Þ', 'ß', 'æ', 'ð', 'þ'),

I do not understand why that shows up as changed since I did not touch that line of code. I would recommend ignoring that change.

Please don't review latest patch. I started refactoring, and found bugs. A newer version is coming soon.

I have put this version through a fair amount of testing, and everything seems to work correctly.

The main difference between this and the previous patch in comment 13 is the that I modified where the code checks for whether the clicked button is a previous or next button by adding an additional case to handle overriding buttons. Thus the check for previous has-beens changed from

if (end($form_state['clicked_button']['#parents']) == 'prev' && $page_num > 1) {
  $page_num--;
}
elseif (end($form_state['clicked_button']['#parents']) == 'next' && $page_num < $page_count) {
  $page_num++;
}

to

if ($page_num > 1 && (end($form_state['clicked_button']['#parents']) == 'prev' || 
  $form_state['clicked_button']['#return_value'] == prev')) {
    $page_num--;
}
elseif ($page_num < $page_count && (end($form_state['clicked_button']['#parents']) == 'next' ||
  $form_state['clicked_button']['#return_value'] == 'next')) {
    $page_num++;
}

And basically the same changes been made for the check for next. Similarly, I modified the check for whether the clicked button is a submit button from

if ($form_state['values']['op'] != $submit_op) {

to

if ($form_state['clicked_button']['#value'] != $submit_op && $form_state['clicked_button']['#return_value'] != submit') {

Obviously, I changed the button and image button components so they provide the correct values for '$form_state['clicked_button']['#return_value'].

In addition, I refactored the code in _webform_client_form_add_component so it uses a loop instead of an if-elseif structure.

Since the above thread has gotten rather long and complicated, I thought it might be useful to write up a description of what this patch does and does not do for webform administrators. So here is some information about the new button and image button components implemented by the above patch.

The button and image button components are useful if you want to:

• choose your own labels for next or previous buttons (you can also do this for submit buttons, but webform already supports that feature)
• use image buttons instead of regular HTML buttons
• allow creation of image buttons through the UI without needing to edit theme or code files
• position your buttons within the stack of webform components rather than below them, for example, if you want the submit button above a markup component containing supplemental information
• have more than one set of buttons, for example, have previous and next buttons both above and below a form's entry fields
• have buttons appear differently on different pages of a multi-page form, for example, "back to 1", "back to 2", etc.

What the new button components do

Since the button and image button are components, you can add as many of them to a webform as you want to, positioning them wherever you want in the stack of components.

Each time you create a new instance of a button or image button component, you choose whether it should function as a previous, next or submit button. This new component will override the default button of the same kind. So, for example, if you add an image button, and set it to work as a submit button, the default submit button will not be added to the form.

Note that overriding one kind of default button does not affect the others. So you could override the previous button with a new component, but continue to use the default next and submit buttons. Also, since button placement is determined on a page by page basis, in a multi-page form, you could replace the default next button on one page, but not on another.

When creating an image button, you enter the path for the image to use. This supports the following tokens: %base, %theme, and %files. Thus once an image is in the filesystem, all you need to know is how to find it starting with either the base path, the path to theme, or the path inside the files folder.

What the new button components do not do

The button and image button components cannot create buttons which function in a way different from the default buttons provided by the webform module. That module provides three kinds of button:

• Submit: appears only on the last page of a form. Its label reads "Submit".
• Next: appears on every page except the last page of a form. Its label reads "Next >"
• Previous: appears on every page except the first page of a form. Its label reads "< Previous".

Similarly, the button and image button components do not support adding buttons which do anything other than submit the form, go to the next page, or go to the previous page.

Since the new button components respect the above logic, if you add a button or image button component in a place where the webform module does not think a button of that kind should appear, the component will not appear. So, for example, if you add an image button to a single-page webform, and set it to go to the previous page, your previous image button will not appear in the form since single-page forms do not support previous buttons.